home *** CD-ROM | disk | FTP | other *** search
/ Merciful 1 / Merciful - Disc 1.iso / software / a / asm_one / asm-onev1.25a.dms / in.adf / Release3.1 / AutoDocs3.1.lha / doc / wb.doc < prev   
Encoding:
Text File  |  1993-08-12  |  12.0 KB  |  380 lines
  1. TABLE OF CONTENTS
  2.  
  3. workbench.library/AddAppIconA
  4. workbench.library/AddAppMenuItemA
  5. workbench.library/AddAppWindowA
  6. workbench.library/RemoveAppIcon
  7. workbench.library/RemoveAppMenuItem
  8. workbench.library/RemoveAppWindow
  9. workbench.library/WBInfo
  10. workbench.library/AddAppIconA                   workbench.library/AddAppIconA
  11.  
  12.    NAME
  13.     AddAppIconA - add an icon to workbench's list of appicons.       (V36)
  14.  
  15.    SYNOPSIS
  16.     AppIcon = AddAppIconA(id, userdata, text, msgport,
  17.        D0              D0     D1      A0     A1
  18.  
  19.                     lock, diskobj, taglist)
  20.                      A2      A3      A4
  21.  
  22.     struct AppIcon *AddAppIconA(ULONG, ULONG, char *,
  23.         struct MsgPort *, struct FileLock *, struct DiskObject *,
  24.         struct TagItem *);
  25.  
  26.     Alternate, varargs version:
  27.     struct AppIcon *AddAppIcon(ULONG, ULONG, char *,
  28.             struct MsgPort *, struct FileLock *,
  29.             struct DiskObject *,
  30.             tag1, data1,
  31.             tag2, data2,
  32.             ...
  33.             TAG_END );
  34.  
  35.    FUNCTION
  36.     Attempt to add an icon to workbench's list of appicons.  If
  37.     successful, the icon is displayed on the workbench (the same
  38.     place disk icons are displayed).
  39.     This call is provided to allow applications to be notified when
  40.     a graphical object (non neccessarely associated with a file)
  41.     gets 'manipulated'. (explained later).
  42.     The notification consists of an AppMessage (found in workbench.h/i)
  43.     of type 'MTYPE_APPICON' arriving at the message port you specified.
  44.     The types of 'manipulation' that can occur are:
  45.     1. Double-clicking on the icon.  am_NumArgs will be zero and
  46.        am_ArgList will be NULL.
  47.     2. Dropping an icon or icons on your appicon.  am_NumArgs will
  48.           be the number of icons dropped on your app icon plus one.
  49.           am_ArgList will be an array of ptrs to WBArg structures.
  50.           Refer to the 'WBStartup Message' section of the RKM for more info.
  51.     3. Dropping your appicon on another icon.  NOT SUPPORTED.
  52.  
  53.    INPUTS
  54.     id - this variable is strictly for your own use and is ignored by
  55.          workbench.  Typical uses in C are in switch and case statements,
  56.          and in assembly language table lookup.
  57.     userdata - this variable is strictly for your own use and is ignored
  58.            by workbench.
  59.     text - name of icon (char *)
  60.     lock - NULL    (Currently unused)
  61.     msgport - pointer to message port workbench will use to send you an
  62.           AppMessage message of type 'MTYPE_APPICON' when your icon
  63.           gets 'manipulated' (explained above).
  64.     diskobj - pointer to a DiskObject structure filled in as follows:
  65.         do_Magic - NULL
  66.         do_Version - NULL
  67.         do_Gadget - a gadget structure filled in as follows:
  68.         NextGadget - NULL
  69.         LeftEdge - NULL
  70.         TopEdge - NULL
  71.         Width - width of icon hit-box
  72.         Height - height of icon hit-box
  73.         Flags - NULL or GADGHIMAGE
  74.         Activation - NULL
  75.         GadgetType - NULL
  76.         GadgetRender - pointer to Image structure filled in as follows:
  77.             LeftEdge - NULL
  78.             TopEdge - NULL
  79.             Width - width of image (must be <= Width of hit box)
  80.             Height - height of image (must be <= Height of hit box)
  81.             Depth - # of bit-planes in image
  82.             ImageData - pointer to actual word aligned bits (CHIP MEM)
  83.             PlanePick - Plane mask ((1 << depth) - 1)
  84.             PlaneOnOff - 0
  85.             NextImage - NULL
  86.         SelectRender - pointer to alternate Image struct or NULL
  87.         GadgetText - NULL
  88.         MutualExclude - NULL
  89.         SpecialInfo - NULL
  90.         GadgetID - NULL
  91.         UserData - NULL
  92.         do_Type - NULL
  93.         do_DefaultTool - NULL
  94.         do_ToolTypes - NULL
  95.         do_CurrentX - NO_ICON_POSITION (recommended)
  96.         do_CurrentY - NO_ICON_POSITION (recommended)
  97.         do_DrawerData - NULL
  98.         do_ToolWindow - NULL
  99.         do_StackSize - NULL
  100.  
  101.     (an easy way to create one of these (a DiskObject) is to create an icon
  102.         with the V2.0 icon editor and save it out.  Your application can then
  103.         call GetDiskObject on it and pass that to AddAppIcon.)
  104.  
  105.     taglist - ptr to a list of tag items.  Must be NULL for V2.0.
  106.  
  107.    RESULTS
  108.     AppIcon - a pointer to an appicon structure which you pass to
  109.           RemoveAppIcon when you want to remove the icon
  110.           from workbench's list of appicons.  NULL
  111.           if workbench was unable to add your icon; typically
  112.           happens when workbench is not running or under low
  113.           memory conditions.
  114.  
  115.    EXAMPLE
  116.     You could design a print-spooler icon and add it to the workbench.
  117.     Any file dropped on the print spooler would be printed.  If the
  118.     user double-clicked (opened) your printer-spooler icon, you could
  119.     open a window showing the status of the print spool, allow changes
  120.     to print priorities, allow deletions, etc.  If you registered this
  121.     window as an 'appwindow' (explained in workbench.library AddAppWindow)
  122.     files could also be dropped in the window and added to the spool.
  123.  
  124.    SEE ALSO
  125.     RemoveAppIcon()
  126.  
  127.    BUGS
  128.     Currently Info cannot be obtained on appicons.
  129.  
  130. workbench.library/AddAppMenuItemA           workbench.library/AddAppMenuItemA
  131.  
  132.    NAME
  133.     AddAppMenuItemA - add a menuitem to workbench's list             (V36)
  134.                          of appmenuitems.
  135.  
  136.    SYNOPSIS
  137.     AppMenuItem = AddAppMenuItemA(id, userdata, text, msgport, taglist)
  138.     D0                  D0     D1      A0     A1       A2
  139.  
  140.     struct AppMenuItem *AddAppMenuItemA(ULONG, ULONG, char *,
  141.                         struct MsgPort *,
  142.                         struct TagItem *);
  143.  
  144.     Alternate, varargs version:
  145.     struct AppMenuItem *AddAppMenuItem(ULONG, ULONG, char *,
  146.                     struct MsgPort *,
  147.                     tag1, data1,
  148.                     tag2, data2,
  149.                     ...
  150.                     TAG_END );
  151.  
  152.    FUNCTION
  153.     Attempt to add the text as a menuitem to workbench's list
  154.     of appmenuitems (the 'Tools' menu strip).
  155.  
  156.    INPUTS
  157.     id - this variable is strictly for your own use and is ignored by
  158.          workbench.  Typical uses in C are in switch and case statements,
  159.          and in assembly language table lookup.
  160.     userdata - this variable is strictly for your own use and is ignored
  161.            by workbench.
  162.     text - text for the menuitem (char *)
  163.     msgport - pointer to message port workbench will use to send you an
  164.           AppMessage message of type 'MTYPE_APPMENUITEM' when your
  165.           menuitem gets selected.
  166.     taglist - ptr to a list of tag items.  Must be NULL for V2.0.
  167.  
  168.    RESULTS
  169.     AppMenuItem - a pointer to an appmenuitem structure which you pass to
  170.               RemoveAppMenuItem when you want to remove the menuitem
  171.               from workbench's list of appmenuitems.  NULL if
  172.               workbench was unable to add your menuitem; typically
  173.               happens when workbench is not running or under low
  174.               memory conditions.
  175.  
  176.    SEE ALSO
  177.     RemoveAppMenuItem()
  178.  
  179.    BUGS
  180.     Currently does not limit the system to 63 menu items...
  181.     Any menu items after the 63rd will not be selectable.
  182.  
  183. workbench.library/AddAppWindowA               workbench.library/AddAppWindowA
  184.  
  185.    NAME
  186.     AddAppWindowA - add a window to workbench's list of appwindows.  (V36)
  187.  
  188.    SYNOPSIS
  189.     AppWindow = AddAppWindowA(id, userdata, window, msgport, taglist)
  190.     D0              D0     D1       A0      A1       A2
  191.  
  192.     struct AppWindow *AddAppWindowA(ULONG, ULONG, struct Window *,
  193.                     struct MsgPort *, struct TagItem *);
  194.  
  195.     Alternate, varargs version:
  196.     struct AppWindow *AddAppWindow(ULONG, ULONG, struct Window *,
  197.                     struct MsgPort *
  198.                     tag1, data1,
  199.                     tag2, data2,
  200.                     ...
  201.                     TAG_END );
  202.  
  203.    FUNCTION
  204.     Attempt to add the window to workbench's list of appwindows.
  205.     Normally non-workbench windows (those not opened by workbench)
  206.     cannot have icons dropped in them.  This call is provided to
  207.     allow applications to be notified when an icon or icons get
  208.     dropped inside a window that they have registered with workbench.
  209.     The notification consists of an AppMessage (found in workbench.h/i)
  210.     of type 'MTYPE_APPWINDOW' arriving at the message port you specified.
  211.     What you do with the list of icons (pointed to by am_ArgList) is
  212.     up to you, but generally you would want to call GetDiskObjectNew on
  213.     them.
  214.  
  215.    INPUTS
  216.     id - this variable is strictly for your own use and is ignored by
  217.          workbench.  Typical uses in C are in switch and case statements,
  218.          and in assembly language table lookup.
  219.     userdata - this variable is strictly for your own use and is ignored
  220.            by workbench.
  221.     window - pointer to window to add.
  222.     msgport - pointer to message port workbench will use to send you an
  223.           AppMessage message of type 'MTYPE_APPWINDOW' when your
  224.           window gets an icon or icons dropped in it.
  225.     taglist - ptr to a list of tag items.  Must be NULL for V2.0.
  226.  
  227.    RESULTS
  228.     AppWindow - a pointer to an appwindow structure which you pass to
  229.             RemoveAppWindow when you want to remove the window
  230.             from workbench's list of appwindows.  NULL
  231.             if workbench was unable to add your window; typically
  232.             happens when workbench is not running or under low
  233.             memory conditions.
  234.  
  235.    SEE ALSO
  236.     RemoveAppWindow()
  237.  
  238.    NOTES
  239.        The V2.0 icon editor is an example of an app window.  Note that app
  240.        window applications generally want to call GetDiskObjectNew
  241.        (as opposed to GetDiskObject) to get the disk object for the icon
  242.        dropped in the window.
  243.  
  244.    BUGS
  245.     None
  246.  
  247. workbench.library/RemoveAppIcon               workbench.library/RemoveAppIcon
  248.  
  249.    NAME
  250.     RemoveAppIcon - remove an icon from workbench's list            (V36)
  251.                          of appicons.
  252.  
  253.    SYNOPSIS
  254.     error = RemoveAppIcon(AppIcon)
  255.          D0                     A0
  256.     BOOL RemoveAppIcon(struct AppIcon *);
  257.  
  258.    FUNCTION
  259.     Attempt to remove an appicon from workbench's list of appicons.
  260.  
  261.    INPUTS
  262.     AppIcon - pointer to an AppIcon structure returned by AddAppIcon.
  263.  
  264.    RESULTS
  265.     error - Currently always TRUE...
  266.  
  267.    NOTES
  268.     As with anything that deals with async operation, you will need to
  269.     do a final check for messages on your App message port for messages
  270.     that may have come in between the last time you checked and the
  271.     call to removed the App.
  272.  
  273.    SEE ALSO
  274.     AddAppIconA()
  275.  
  276.    BUGS
  277.     None
  278.  
  279. workbench.library/RemoveAppMenuItem       workbench.library/RemoveAppMenuItem
  280.  
  281.    NAME
  282.     RemoveAppMenuItem - remove a menuitem from workbench's list      (V36)
  283.                 of appmenuitems.
  284.  
  285.    SYNOPSIS
  286.     error = RemoveAppMenuItem(AppMenuItem)
  287.          D0                            A0
  288.     BOOL RemoveAppMenuItem(struct AppMenuItem *);
  289.  
  290.    FUNCTION
  291.     Attempt to remove an appmenuitem from workbench's list
  292.     of appmenuitems.
  293.  
  294.    INPUTS
  295.     AppMenuItem - pointer to an AppMenuItem structure returned by
  296.               AddAppMenuItem.
  297.  
  298.    RESULTS
  299.     error - Currently always TRUE...
  300.  
  301.    NOTES
  302.     As with anything that deals with async operation, you will need to
  303.     do a final check for messages on your App message port for messages
  304.     that may have come in between the last time you checked and the
  305.     call to removed the App.
  306.  
  307.    SEE ALSO
  308.     AddAppMenuItemA()
  309.  
  310.    BUGS
  311.     None
  312.  
  313. workbench.library/RemoveAppWindow           workbench.library/RemoveAppWindow
  314.  
  315.    NAME
  316.     RemoveAppWindow - remove a window from workbench's list         (V36)
  317.                           of appwindows.
  318.  
  319.    SYNOPSIS
  320.     error = RemoveAppWindow(AppWindow)
  321.          D0                       A0
  322.     BOOL RemoveAppWindow(struct AppWindow *);
  323.  
  324.    FUNCTION
  325.     Attempt to remove an appwindow from workbench's list of appwindows.
  326.  
  327.    INPUTS
  328.     AppWindow - pointer to an AppWindow structure returned by
  329.             AddAppWindow.
  330.  
  331.    RESULTS
  332.     error - Currently always TRUE...
  333.  
  334.    NOTES
  335.     As with anything that deals with async operation, you will need to
  336.     do a final check for messages on your App message port for messages
  337.     that may have come in between the last time you checked and the
  338.     call to removed the App.
  339.  
  340.    SEE ALSO
  341.     AddAppWindowA()
  342.  
  343.    BUGS
  344.     None
  345.  
  346. workbench.library/WBInfo                             workbench.library/WBInfo
  347.  
  348.    NAME
  349.     WBInfo - Bring up the Information requrester                     (V39)
  350.  
  351.    SYNOPSIS
  352.     worked = WBInfo(lock, name, screen)
  353.     d0              a0    a1    a2
  354.  
  355.     ULONG WBInfo(BPTR, STRPTR, struct Screen *);
  356.  
  357.    FUNCTION
  358.     This is the LVO that Workbench calls to bring up the Icon Information
  359.     requester.  External applications may also call this requester.
  360.     In addition, if someone were to wish to replace this requester
  361.     with another one, they could do so via a SetFunction.
  362.  
  363.    INPUTS
  364.     lock   - A lock on the parent directory
  365.     name   - The name of the icon contained within above directory
  366.     screen - A screen pointer on which the requester is to show up
  367.  
  368.    RESULTS
  369.     worked - Returns TRUE if the requester came up, FALSE if it did not.
  370.  
  371.    NOTE
  372.     Note that this LVO may be called many times by different tasks
  373.     before other calls return.  Thus, the code must be 100% re-entrant.
  374.  
  375.    SEE ALSO
  376.     icon.library
  377.  
  378.    BUGS
  379.  
  380.